home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr50 / datema.zip / DATECALC.TXT < prev    next >
Text File  |  1993-01-21  |  13KB  |  339 lines
  1.             DATEMATH
  2.         Working Days Calculator
  3.             (c) 1993
  4.  
  5.  
  6.  
  7.  
  8.  
  9.         Table of Contents
  10.  
  11.     1. Introduction (What Is DATEMATH ?)
  12.  
  13.     2. A Simple Tutorial
  14.  
  15.     3. The Calendar Text File
  16.  
  17.     4. Compiling the Calendar File
  18.  
  19.     5. DATEMATH's Library Functions
  20.  
  21.     6. Oddities of Calendar Math
  22.  
  23.     7. Coming Soon From Expertec
  24.  
  25.     8. Registration & Legal Info
  26.  
  27.  
  28.  
  29.  
  30.  
  31. 1. Introduction (What Is DATEMATH ?)
  32. -----------------------------------------------------------------------
  33.  
  34. DATEMATH is a dynamic link library that allows developers to give their
  35. applications the ability to real date math. While most programming 
  36. languages give you some minimal capabilities for date manipulation, 
  37. DATEMATH will allow you to add accuracy to your programs. 
  38. For instance, most language products could tell you that there is 59 days 
  39. between Jan 1, 1993 and Mar 1, 1993. But while DATEMATH can tell you that, 
  40. it can also tell you that there is 39 work days between those dates. 
  41. ( If company allows more holidays, the number of work days 
  42. could be even less ). 
  43.  
  44. There are three basic elements to DATEMATH. They are:
  45.     A. The DATEMATH DLL
  46.     B. The Calandar Text File
  47.     C. The Calendar Binary File 
  48.  
  49. A. The DATEMATH DLL handles the three eccential date functions consisting
  50. of DCalDIF ( a function that returns  the difference in working days
  51. between two dates), DCalADD (a function that allows you to add x number
  52. of work days to a start date and returns the finish date), and
  53. DCalSUB ( a function that allows you to subtract x number of work days
  54. from a finish date and returns the start date). DATEMATH also includes
  55. functions for loading and unloading various user calendars. Registered
  56. users of DATEMATH will also be given access to additional functions in
  57. DATEMATH as well as a Calendar Maintanence program.
  58.  
  59. B. The Calendar Text File is a simple ASCII file that contains a listing
  60. of the two basic rest types, namely Rest Days and Holidays. An example
  61. of a Rest Day is SUNDAY. Rest Days refer to Days of the Week. An example
  62. of a Holiday is 12/25/93. Holidays refer to a specific date in time. More
  63. on the calendar text files later.
  64.  
  65. C. The Calendar Binary File is produced when the program CalMaint.EXE
  66. compiles the calendar text file. The DATEMATH DLL reads the calendar
  67. binary file when the LoadCalendar Function is called. The program
  68. CalMaint.EXE is a windows based program that is not included with
  69. the demo version of DATEMATH. However when you register DATEMATH you
  70. will recieve a copy of the CalMaint program at no additional cost. 
  71. More on this later. 
  72.  
  73.  
  74. 2. A Simple Tutorial
  75. ---------------------------------------------------------------------
  76.  
  77. When you start the program the cursor will blinking in a text box labeled
  78. start date. Type 1/1/93 and hit the {TAB} key. In the next box type
  79. 2/1/93 and hit the {TAB} key. Next Click the Difference button and
  80. note the answer in the Results box. Next try selecting different calendars
  81. from the Calendar Group box. As you select different calendars the results
  82. boxes will clear. Click again on the Difference and note the new results.
  83. Its that simple. 
  84.  
  85.  
  86. 3. The Calendar Text File
  87. ---------------------------------------------------------------------
  88.  
  89. The Calendar Text is a simple text file that allows the developer to
  90. define up to eight seperate work calendars. The Calendar text holds
  91. calendar names and their respective rest and holiday information. 
  92. There is three types of data that can be in a calendar text file. They
  93. are Rest Lines, Holiday Lines and Comment Lines. 
  94.  
  95. Rest Lines and Holiday Lines are made up of two parts. The first part
  96. is the calendar name and the second part is the day value.
  97.  
  98. Here are some examples of Rest Lines:
  99.                 FiveDay Saturday
  100.                 FiveDay Sunday
  101. In the above example we have created a calendar called FiveDay and
  102. specified Saturday and Sunday as rest days. Please note the calendar
  103. name 'FiveDay'. One of the only rules we have when your using DATEMATH
  104. is that calendar names cannot exceed 8 characters and the first character
  105. must be a letter.
  106.  
  107. Here are some examples of Holiday Lines:
  108.                 FiveDay    18-Jan-93
  109.                 FiveDay 15-Feb-93
  110. In this example we have specified 18-Jan-93 ( Dr. Martin Luther Kings
  111. Birthday ) and 15-Feb-93 ( Presidents Day ) as non-work days. Each
  112. calendar can have up to 200 holidays.
  113.  
  114. Here are some example of Comment lines
  115.             // Anything That Doesn't Look
  116.             */ Like a Rest or Holiday
  117.             ; line gets interpeted as a Comment.
  118.  
  119. Below is the Calendar Text File Used in the Sample application.
  120.  
  121. //This is the Calendar Text File (CALDATA.TXT).
  122. // Note that the file can contain blank lines for clarity
  123.  
  124. //First I will set up a 5 day work week calendar called FiveDay.
  125. //Calendar names can be up to 8 characters long and MUST start
  126. //with a letter. 
  127.  
  128. //Calendar FiveDay will have rest on Saturday and
  129. //Sunday but no holidays.
  130.  
  131. //Holidays for FiveDay
  132.  
  133. //Rest for FiveDay
  134. FiveDay sat
  135. FiveDay sun
  136.  
  137.  
  138. //Next I will set up a six day calendar that rests only on Sunday
  139. //and has no holidays.
  140.  
  141. //Holidays for SixDay
  142.  
  143. //Rest for SixDay
  144. SixDay sun
  145.  
  146.  
  147. //Finally I will setup a calendar that rests on Saturday and Sunday
  148. //and has standard US Holidays for 1993.
  149.  
  150. //Holidays for HolsFive
  151. HolsFive 18-jan-93
  152. HolsFive 25-feb-93
  153. HolsFive 31-may-93
  154. HolsFive 5-jul-93
  155. HolsFive 6-sep-93
  156. HolsFive 11-nov-93
  157. HolsFive 25-nov-93
  158. HolsFive 24-dec-93
  159. HolsFive 31-dec-93
  160.  
  161. //Rest for HolsFive
  162. HolsFive sat
  163. HolsFive sun
  164.  
  165.  
  166.  
  167. 4. Compiling the Calendar File
  168. ---------------------------------------------------------------------
  169.  
  170. Before DATEMATH can use the user defined calendars, the calendar text
  171. text file must be compiled. This is done with the program CalMaint.EXE.
  172. CalMaint first examines the calendar text file and produces a matrix
  173. display of the users calendars. Once the you is statisfied with the
  174. results CalMaint will compile the text file into a binary. The default
  175. name for the Calendar Text file is Caldata.TXT. The default name for
  176. the calendar binary file is Caldata.BIN. 
  177. The program CalMaint.EXE is not included in the demo version of 
  178. DATEMATH. However the user may test the software completely in there
  179. own programs with the Caldata.BIN file provided. As shown in the 
  180. previous section, this calendar file has three user defined work
  181. calendars in it. 
  182.  
  183. 1. FiveDay - Rest on Saturdays & Sundays, No Holidays
  184. 2. SixDay  - Rest on Sundays, No Holidays
  185. 3. HolsFive- Rest on Saturdays & Sundays plus Std US Holidays for 1993
  186.  
  187. If you choose to register DATEMATH you will recieve CalMaint.exe ( so
  188. you can compile your own calendars ) at no extra cost.
  189.  
  190.  
  191.  
  192. 5. DATEMATH's Library Functions
  193. ---------------------------------------------------------------------
  194.  
  195. The five functions included in the DATEMATH DLL are as follows:
  196.  
  197. Function Name        Ord  Rcv/Snd          Type        Parameter    Description/Sample
  198. ---------------------   ---  -------            -----           ---------       -------------------
  199. LoadCalendar        1    (R)        LPINT        nMemRef        memory tag
  200.                 (S)        LPSTR        szCalFile    'c:\caldata.bin'
  201. DCalDIF            2    (S)        LPINT        nMemRef        memory tag
  202.                 (S)        LPSTR        szCalendar    'ADMIN'
  203.                 (S)        LPSTR        szStartDate    '1993-01-01'
  204.                 (S)        LPSTR        szFinDate    '1993-01-31'
  205.                 (R)        LPINT        nDaysDif    result difference in days
  206. DCalADD            3    (S)        LPINT        nMemRef        memory tag
  207.                 (S)        LPSTR        szCalendar    'ADMIN'
  208.                 (S)        LPSTR        szDateIn    '1993-01-01'
  209.                 (R)        LPSTR        szDateOut    date result
  210.                 (S)        LPINT        nDaysAmt    days to add    
  211. DCalSUB            4    (S)        LPINT        nMemRef        memory tag
  212.                 (S)        LPSTR        szCalendar    'ADMIN'
  213.                 (S)        LPSTR        szDateIn    '1993-01-01'
  214.                 (R)        LPSTR        szDateOut    date result
  215.                 (S)        LPINT        nDaysAmt    days to substract
  216. DestroyCalendar        5    (R)        LPINT        nMemRef        releases calendar memory
  217.  
  218.  
  219. They are defined in Visual Basic AS:
  220.  
  221. Declare Function LoadCalendar Lib "DateMath.DLL" (nMemRef%, ByVal szCalFile$) As Integer
  222. Declare Function DCalDIF Lib "DateMath.DLL" (nMemRef%, ByVal szCalendar$, ByVal szStart$, ByVal szFinish$, nDaysDif%) As Integer
  223. Declare Function DCalADD Lib "DateMath.DLL" (nMemRef%, ByVal szCalendar$, ByVal szStart$, ByVal szFinish$, nDaysDif%) As Integer
  224. Declare Function DCalSUB Lib "DateMath.DLL" (nMemRef%, ByVal szCalendar$, ByVal szStart$, ByVal szFinish$, nDaysDif%) As Integer
  225. Declare Function DestroyCalendar Lib "DateMath.DLL" (nMemRef%) As Integer
  226.  
  227.  
  228. 6. Oddities of Calendar Math
  229. ---------------------------------------------------------------------
  230.  
  231. If you're new to doing 'Work Day' calendar math you may occasionally
  232. come across results you don't expect. The best way to illustrate 
  233. this is with an example.
  234.  
  235. First lets consider the months of January 1993 & February 1993.
  236.  
  237.    January 1993            February 1993
  238. Su Mo Tu We Th Fr Sa   Su Mo Tu We Th Fr Sa
  239.                 1  2       1  2  3  4  5  6
  240.  3  4  5  6  7  8  9    7  8  9 10 11 12 13
  241. 10 11 12 13 14 15 16   14 15 16 17 18 19 20
  242. 17 18 19 20 21 22 23   21 22 23 24 25 26 27
  243. 24 25 26 27 28 29 30   28
  244. 31
  245.  
  246. Assuming that all Saturdays and Sundays are rest days, consider the
  247. following two statements:
  248.  
  249. The difference between 1-Jan-93 and 31-Jan-93 is 21 work days.
  250. The difference between 1-Jan-93 and  1-Feb-93 is 21 work days.
  251.  
  252. Both these statemnts are true. ( Since 31-Jan-93 is a rest day)
  253.  
  254. Continuing along line, consider these statements:
  255.  
  256. 1-Jan-93  plus  21 work days equals 1-Feb-93.
  257. 31-Jan-93 minus 21 work days equals 1-Jan-93.
  258.  
  259. When adding or subtracting work days from a date the result is
  260. always a work day.
  261.  
  262. Hopefully this breif explantion will help you if you find yourself
  263. confused about the results DATEMATH produces.
  264.  
  265.  
  266.  
  267. 7. Coming Soon From Expertec
  268. ---------------------------------------------------------------------
  269.  
  270. Expertec Incorporated has been in the business of writing custom
  271. software for Fortune 500 companies since 1989. At Expertec we
  272. specialize in the development of Project Management and Expert
  273. Systems. The majority of our work is in the client-server arena
  274. primarily on Windows,Windows NT, and Unix platforms.
  275.  
  276. DATEMATH comes from the Project Management side of the house and
  277. is primarily the of work Paul Onstad. Another of Mr. Onstads programs
  278. that may be of interest is the Expertec CPM Engine. The CPM Engine
  279. is a set of DLL's that allow the developer to perform Critical
  280. Path Analysis routines on there databases. The product generates
  281. all standard CPM dates including Early Start, Early Finish,
  282. Late Start, Late Finish as well as Total and Free floats. The CPM
  283. engine also allows six different Target Date types and uses the same
  284. calendar files as DATEMATH. The product is currently available
  285. for developers using Gupta Technologies SQLWindows language and will
  286. be available for Microsoft Access developers in the 2nd Qtr. 1993.
  287. Suggested Retail Price for the CPM engine is $99.95
  288.  
  289. 8. Registration & Legal Info
  290. ---------------------------------------------------------------------
  291.  
  292. Money Stuff:
  293.  
  294. DATEMATH is not free.  It is a commercial Shareware product.  You
  295. are permited to evaluate this product for 15 days.  After that time 
  296. you must register or discontinue using the program.  
  297. The use of unregistered copies of DATEMATH, beyond the evaluation 
  298. period, by any person, business, corporation, government agency or 
  299. any other entity is strictly prohibited.  The basic registration fee 
  300. for DATEMATH  is $24.95($15.00 before 31-Mar-93).  For instructions 
  301. on how to register, see the file REGISTER.TXT.  
  302.  
  303. Whether or not you choose to register, I'd enjoy hearing your comments 
  304. on the program.  Please send all suggestions, gripes, bug reports and 
  305. anything else to any of these addresses:
  306.  
  307. Expertec, Inc.
  308. Attn: Chet Kloss
  309. 340 North Main Street - Suite 304
  310. Plymouth, MI 48170
  311.  
  312. CIS:    72311,743
  313.  
  314. The latest version of DATEMATH can be found on the MSBASIC forum of CIS.
  315.  
  316.  
  317. Legal Stuff:
  318.  
  319. No guarantee is made, expressed or implied, pertaining to the use, 
  320. misuse,or any problems caused by this program.  Should the program 
  321. prove defective, the purchaser or evaluator assumes the risk of paying 
  322. the entire cost of all necessary servicing, repair, or correction, and 
  323. any incidental or consequential damages.  In no event will the author 
  324. be liable for any damages whatsoever arising out of the use or the 
  325. inability to use this product.
  326.  
  327. A limited license is granted to copy and distribute DATEMATH for
  328. the evaluation use of others, as long as it is distributed without
  329. modification, complete with all files.  No fee, charge or other 
  330. compensation may be requested with these exceptions:  
  331. Operators of electronic bulletin board systems may make DATEMATH 
  332. available for downloading, so long as there is no specific charge 
  333. for the download of DATEMATH. Vendors of user-supported or shareware 
  334. software may distribute DATEMATH, so long as any duplication and 
  335. handling fees do not exceed five dollars, and notice is clearly given 
  336. that such fees do not grant the evaluator a license to use DATEMATH 
  337. beyond the evaluation period.
  338.  
  339.